PHLEGM v4 Architecture
======================

Authority
---------
The .phlegm definition files are authoritative source data. PHLEGM compiles them when selected; changing definitions does not require recompiling the FreeBASIC executable.

Execution pipeline
------------------
CFG text -> validation -> symbolic resolution -> numeric VM operations -> generic superinstruction optimization -> opcode program fusion -> decoder/device/bus compilation -> execution.

The runtime hot path does not tokenize instruction/device scripts. This is a CFG-to-VM compiler, not a chip-specific native-code JIT.

CPU root
--------
cfg/chipset/<family>/<variant>/ only. cfg/cpu is not supported.

Machine composition
-------------------
Complete machines combine CPU, support devices, firmware, display, audio, input, bus maps/mirrors, and media. A 64 KiB dispatch table resolves CPU address routing.

Persistence
-----------
States: PHLEGM-STATE-V4 / format 4.
Sessions: PHLEGM-SESSION-V4 / format 4.
Earlier PHLEGM formats are rejected.

Validation policy
-----------------
Normal compile: quick runtime smoke.
Explicit full validation: -FullSelfTest / --selftest-all.
Compiler only: -SkipSelfTest.

Resident PHLEGM compilation lifecycle (v4)
-------------------------------------------
* Synchronization installs source definitions only; it does not compile a running machine.
* Selecting a machine performs one preparation phase before machine activation: machine,
  CPU, support-device, display/filter, and binding definitions are parsed, validated, and
  compiled into numeric resident runtime structures.
* Once machine activation begins, runtime execution, filter switching, STATE-LOAD, and
  SESSION-LOAD never reopen or recompile matching PHLEGM source. They reuse the resident
  compiled definition image for the life of the process/session.
* Loading a session/state in a fresh process, or one targeting a different machine/chipset,
  compiles that target first and only then consumes the saved mutable payload.
* A newly selected machine/chipset replaces the previous resident definition image. Source
  changes therefore take effect at the next explicit machine/chipset load, never halfway
  through an active session.
